Materialize per-layer artifacts with explicit whiteout handling - #456

tldr

Content-addressed per-layer artifact store at images/layers/<layer-blob-digest>/. Pulls and composition (next PR in the stack) share it. Native layer artifacts are Linux-root-only; rootless Linux and macOS use the merged-rootfs path instead, with no image-content change.

what this adds

1. Materialization (materializeLayerArtifact) — unpacks a layer blob from the existing shared OCI cache with umoci, converts to erofs, installs layer.erofs + an artifact.json record atomically. Same layer shared across images materializes once; concurrent callers share one build (singleflight), with a manager-level concurrency bound.
2. Whiteouts as overlayfs — on supported Linux hosts, .wh.<name> becomes a 0:0 char device and .wh..wh..opq becomes a trusted.overlay.opaque xattr. This is the standard representation required by later overlayfs stacking; it is not attempted where the host cannot create it.
3. Platform fallback contract — a startup probe verifies Linux mknod and trusted overlay xattr support on the layer-store filesystem. Rootless Linux, macOS, and unsupported filesystems skip per-layer artifact materialization and compose OCI layers into one rootfs with DirRootfs, which applies whiteouts in userspace. This preserves image semantics while giving up per-layer sharing on those hosts.
4. Hardened extraction — umoci confines entries, blob digest + diff ID verified, stream capped at 100 GiB, detached builds bounded by a 1h deadline.
5. Disk accounting — the layer store, including records and in-progress extraction/install trees, is counted in TotalOCICacheBytes (conservative: blob + artifact of the same layer may transiently coexist). Active builds keep totals uncached, and disk-usage scans retry if invalidated while a scan is in progress.

review status: done

Two independent review passes (correctness + code-quality). Findings and how they are handled:

• Hung blob read could wedge the singleflight key forever → 1h deadline on detached builds
• Cache blob integrity was never verified → unpack now checks the compressed digest
• Rootless/macOS whiteout extraction could not produce valid overlayfs artifacts → unsupported hosts now use the merged-rootfs fallback
• Disk-usage invalidation could return stale totals → scans retry after a concurrent invalidation
• Same-size artifact corruption was reusable → records now include and verify an artifact checksum
• Detached layer builds were unbounded across distinct digests → a manager-level semaphore limits them
• Compressed blob verification could miss decoder-unconsumed suffixes → the raw blob is hashed independently
• Layer-build cleanup could race disk accounting → cleanup completes before the build is marked inactive
• Conflicting descriptor encodings could share one artifact path → records store the normalized encoding and reject mismatches
• Dead/simplification cleanup: composeOnDiskFormat + whiteoutPrefix moved to tests, multiCloser deleted, blob path via paths.OCICacheBlob

Verified empirically on a dev host: mkfs.erofs 1.8.10 and mkfs.ext4 both preserve whiteout char devices and opaque xattrs through ExportRootfs on the supported Linux-root path. Depends on host erofs-utils version; check it in the pull-integration PR.

reviewer focus (3 things)

1. layerBuildTimeout = 1h is a judgment call — flag if hypeman has a convention for bounding background work
2. Unpack now hard-fails on blob digest mismatch — new error if any path intentionally writes unverified blobs
3. PR #458 wires the store into production. It skips layer materialization on unsupported hosts and retains blob-based merged-rootfs composition as the fallback.

validation

Full lib/images + lib/paths green on a rootless host; capability-gated whiteout/device tests pass or skip based on an actual mknod + trusted-xattr probe. Tests cover: materialize/reuse/rebuild, corrupt-record recovery, same-size artifact corruption, invalid digest rejection (sha256:.., sha256:a/b), whiteout/opaque output and cross-layer semantics, symlink confinement and replacement, hardlinks, cancellation, zstd + docker media types, concurrent singleflight (8 callers, one build), trailing-padding diff IDs. The exported erofs whiteout round trip moves to the composition PR, which is where the host erofs-utils version gets checked.

CI note: the test workflow is flaky on this branch — failures are unrelated integration tests (TestEgressProxyRewritesHTTPSHeaders timeout, docker/network tests needing nginx:alpine), failing before the latest commits too. Layer-artifact tests pass consistently.

next step

Review the focus items above, then approve. PR #458 is the production caller and lifecycle follow-up.